Skip to content

Add Docker Support for Easy Installation and Deployment #4559

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: 3.x
Choose a base branch
from
Open

Add Docker Support for Easy Installation and Deployment #4559

wants to merge 1 commit into from

Conversation

PolNavarro
Copy link
Contributor

Add Docker Support for Easy Installation and Deployment

Summary

This pull request adds comprehensive Docker support to Cachet v3, making installation and deployment significantly easier for users. The Docker setup includes a complete production-ready environment with Nginx, PHP-FPM, MySQL, and Redis.

What's Included

Core Docker Files

  • Dockerfile - Production-ready multi-stage build with PHP 8.3, Nginx, and all required extensions
  • docker-compose.yml - Complete orchestration with app, database, and Redis services
  • .env.docker.example - Template environment file for Docker deployment
  • DOCKER.md - Comprehensive documentation and setup instructions

Docker Configuration

  • docker/nginx/nginx.conf - Optimized Nginx configuration for Laravel/Filament
  • docker/php/cachet.ini - PHP optimizations for production
  • docker/supervisor/supervisord.conf - Process management for Nginx, PHP-FPM, and queue workers
  • docker/entrypoint.sh - Startup script with database migrations and caching

Why Docker Support?

  1. Simplified Installation - One command deployment instead of complex manual setup
  2. Consistent Environment - Same setup works across development, staging, and production
  3. Dependency Management - All required services (MySQL, Redis) included and configured
  4. Production Ready - Optimized for performance with proper security practices
  5. Easy Scaling - Ready for container orchestration and load balancing

Features

Security Best Practices

  • Internal network communication (MySQL/Redis not publicly exposed)
  • Proper file permissions and user management
  • Secure environment variable handling
  • Production-optimized PHP and Nginx configurations

Production Optimizations

  • Multi-stage Docker build for smaller images
  • Composer optimizations and dependency caching
  • PHP OPcache enabled
  • Nginx static file serving optimizations
  • Health checks for all services

Easy Setup

# Clone and setup
git clone https://github.com/cachethq/cachet.git
cd cachet

# Configure environment
cp .env.docker.example .env
# Edit .env with your passwords and domain

# Deploy with one command
docker-compose up -d --build

# Generate application key
docker-compose exec app php artisan key:generate

Architecture

The Docker setup uses a 3-service architecture:

  1. app - Cachet application (Nginx + PHP-FPM)
  2. db - MySQL 8.0 database
  3. redis - Redis 7 for caching and sessions

All services communicate via a private Docker network with health checks ensuring proper startup order.

Benefits for Users

  • Quick Start: Get Cachet running in minutes instead of hours
  • Consistent Setup: Eliminates "works on my machine" issues
  • Easy Updates: Simple container rebuilds for new versions
  • Development Friendly: Perfect for testing and development environments
  • Production Ready: Scales from single server to orchestrated deployments

Testing

The Docker setup has been thoroughly tested and includes:

  • ✅ Successful database migrations
  • ✅ Redis connectivity with Predis client
  • ✅ Nginx + PHP-FPM communication
  • ✅ Filament admin panel accessibility
  • ✅ Static asset serving
  • ✅ Environment variable configuration
  • ✅ Health checks and dependency management

Documentation

Complete setup instructions are provided in DOCKER.md covering:

  • Quick start guide
  • Environment configuration
  • Production deployment
  • Troubleshooting
  • Security considerations
  • Scaling instructions

Future Enhancements

This Docker foundation enables:

  • Kubernetes deployment manifests
  • Docker Hub automated builds
  • CI/CD integration
  • Multi-stage environments (dev/staging/prod)
  • Container monitoring and logging

Conclusion

This Docker implementation makes Cachet more accessible to users by eliminating complex setup procedures. It provides a production-ready foundation that can grow from simple single-server deployments to complex orchestrated environments.

We believe this addition will significantly improve the user experience and adoption of Cachet v3.

Files Changed:

  • Added: Dockerfile
  • Added: docker-compose.yml
  • Added: .env.docker.example
  • Added: DOCKER.md
  • Added: docker/nginx/nginx.conf
  • Added: docker/php/cachet.ini
  • Added: docker/supervisor/supervisord.conf
  • Added: docker/entrypoint.sh

@PolNavarro
Add comprehensive Docker support for easy installation and deployment
49a4e49 
This commit introduces complete Docker support for Cachet v3, making
installation and deployment significantly easier for users.

Features:
- Production-ready Dockerfile with PHP 8.3, Nginx, and all dependencies
- Docker Compose orchestration with MySQL 8.0 and Redis 7
- Optimized configurations for security and performance
- Comprehensive documentation with setup instructions
- Health checks and proper service dependencies
- Internal network security (no exposed database ports)

Benefits:
- One-command deployment: `docker-compose up -d --build`
- Consistent environment across dev/staging/production
- Eliminates complex manual setup procedures
- Production-ready with security best practices
- Easy scaling and container orchestration ready

Files added:
- Dockerfile: Multi-stage production build
- docker-compose.yml: Complete service orchestration
- .env.docker.example: Environment template
- DOCKER.md: Comprehensive setup documentation
- docker/: Configuration files for Nginx, PHP, and Supervisor
@jbrooksuk
Copy link
Member

@egelhaus this is great, thank you! Cachet 2.x previously had all Docker stuff located in the cachethq/docker repository. Do you think it makes sense to continue locating all of this there?

@PolNavarro
Copy link
Contributor Author

Good, it can be done both ways. I personally prefer to have it all together in the same repo.

Basically, you can pass test with docker, basing commits or pull requests with github actions, from any branch. You know if it works or not. Also for me the most important thing, if you want them to use your software, the easier the better.

@egelhaus
Copy link

Hey @jbrooksuk ,
I didn't made the PR, @PolNavarro is the owner, I simply reviewed it.
But as @PolNavarro said, I'd prefer to have it in the same repo too.

egelhaus
egelhaus reviewed Jul 25, 2025
View reviewed changes
Copy link

@egelhaus egelhaus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An pre-built docker image via GitHub CI pushed to GHCR would also make sense.

@steffjenl
Copy link
Collaborator

As a software developer, I also prefer having everything in the same repository as the software. But from the perspective of a non-developer or a system administrator, what would I want to do with the source code? In that case, I’d rather have a clean repository containing just a docker-compose.yml and a Kubernetes deployment file.

I also prefer using a pre-built image. Today, I cleaned up my PR a bit because it still had some old commits from version 2.4.
See: cachethq/Docker#434

My preference is to keep the webserver, scheduler, and workers separate so that in larger deployments (with many subscribers), you can scale out by running multiple workers.

The scheduler is separated because artisan schedule:run should only run on a single container to avoid duplicate task execution.

Ultimately, you’ll also want to create templates for Portainer, Coolify, etc., and that’s why having a separate repository is more practical than trying to cram everything into one.

@ElGigi
Copy link

ElGigi commented Oct 15, 2025 •
edited
Loading

Great work on this PR — the Docker setup is clean and will make running Cachet much easier.

One idea you might consider for deployments that want stricter role separation (compose/Kubernetes): split the current entrypoint.sh into smaller, role-specific scripts (e.g. entrypoint-web.sh, entrypoint-worker.sh, entrypoint-scheduler.sh) plus a tiny top-level entrypoint.sh that can delegate.

That way, when someone wants to isolate web / workers / scheduler as separate services or pods, they can simply switch the entrypoint per service (or container) without touching the image or codebase. It also makes scaling and health checks per role more straightforward.

Again, thanks for the excellent work here!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

1 more reviewer

@egelhaus egelhaus egelhaus approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@PolNavarro @jbrooksuk @egelhaus @steffjenl @ElGigi